home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / cli / foreach.lha / foreach.doc < prev    next >
Text File  |  1994-07-20  |  4KB  |  152 lines
  1.  
  2.                         Foreach - Deluxe
  3.                         ================
  4.  
  5.                            Version 1.0
  6.                             (31.3.94)
  7.  
  8.  
  9. This foreach-command makes it possible to use commands, that don't
  10. support any pattern-matching (like 'rename'). I am sure that you
  11. will not want to miss this powerful command again in future.
  12.  
  13.  
  14. Synopsis:
  15. ---------
  16.  
  17.   foreach <pattern> <command>
  18.  
  19.  
  20. Introduction:
  21. -------------
  22. I think the best way to learn the command is to demonstrate it
  23. first with some examples to allow you to see how the command works:
  24.  
  25.  
  26. - Display all files ending with .c using 'more':
  27.  
  28.   foreach #?.c more &
  29.  
  30.   In this case the pattern is #?.c . The command will now be called
  31.   for each file that matches the pattern, replacing the '&'-character
  32.   with the filename each time.
  33.  
  34.  
  35. - Unarchive all #?.lha und #?.lzh files into the RamDisk:
  36.  
  37.   foreach #?.(lha|lzh) lha x & ram:
  38.  
  39.  
  40. - Replace the suffixes .lzh with .lha on all files:
  41.  
  42.   foreach #?.lzh rename & &<.lha
  43.  
  44.   This is new! The token '&<' will (unlike the plain '&') expand to the
  45.   filename without the suffix.
  46.  
  47.  
  48. - Copying a file three times:
  49.  
  50.   foreach {copy1,copy2,copy3} copy source &
  51.  
  52.   Produces three copies with the names copy1,copy2 and copy3.
  53.  
  54.  
  55. - Compiling of all #?.cc files with gcc:
  56.  
  57.   foreach #?.cc gcc $
  58.  
  59.   Please note that the '$'-character will expand to all matching files
  60.   unlike '&', which expands to only one of the matching files each time.
  61.   Accordingly only one command will be generated, that could look like
  62.   this: ( gcc file1.cc file2.cc file3.cc )
  63.  
  64.  
  65.  
  66. reference:
  67. ----------
  68.  
  69.   &  - will be replaced with a string matching the pattern (eg. a filename)
  70.        in each command that will be generated.
  71.  
  72.   &< - like '&', but this time the suffix will be cut off (the last suffix
  73.        if there are more than one dots). If there is no dot in the name,
  74.        the complete string will be used (like '&').
  75.  
  76.   &> - like '&', but this time only the suffix without the filename. If
  77.        there is no suffix, an empty string (not even a space) will be used.
  78.  
  79.   $  - will be replaced with all matching strings at the same time,
  80.        separated with a space between each of them (no space at the
  81.        beginning and ending).
  82.  
  83.   && - will be replaced with a single '&'-character.
  84.  
  85.   %  - will be replaced with an empty string.
  86.  
  87.  
  88.  
  89. notes:
  90. ------
  91.  
  92.  - There may even be empty strings in the set-argument. For example:
  93.    {} or {aaa,aa,a,}.
  94.  
  95.  - Mind that you have to place quotation marks around the set if it
  96.    contains any string with spaces, as the command-line parser cuts
  97.    the arguments at spaces:
  98.    wrong:  {James,Judy,Mr Bean}
  99.    right: "{James,Judy,Mr Bean}"
  100.  
  101.  - As soon as there is at least one '&'-character in the command string,
  102.    several independent commands will be generated. (ie. are there only
  103.    '$'-characters in the command string, only one command will be
  104.    generated).
  105.  
  106.  
  107. hints:
  108. ------
  109.  
  110.  - It is possible to chain several 'foreach'-commands making the
  111.    'foreach'-command even more powerful.
  112.  
  113.    Example: Creating two backups of all #?.c files:
  114.  
  115.      foreach #?.c foreach {bak1,bak2} copy & &<.&&
  116.  
  117.    Note that the first 'foreach' replaces the '&&' to a singe '&'.
  118.    The second 'foreach' will look like this:
  119.      foreach {bak1,bak2} file1.c file1.&
  120.  
  121.  
  122.  - The '%'-character's main purpose is to solve ambiguities.
  123.    E.g.: You want to write a string two times without any spaces in
  124.          between:
  125.          wrong: foreach {hello,hi,goodmorning} echo &&
  126.          right: foreach {hello,hi,goodmorning} echo &%&
  127.  
  128.  
  129. Copyright:
  130. ----------
  131.   This program is public domain. It may be copied only if the program and
  132.   this manual have not be modified in any way. The program must never be
  133.   copied without the manual.
  134.   The program must not be sold or included in a commercial product without
  135.   my permission (write or EMail me).
  136.  
  137.  
  138.   Dirk Farin
  139.   Kapellenweg 15
  140.   72070 Tübingen
  141.   Germany
  142.  
  143.   EMail:      farindk@trick.informatik.uni-stuttgart.de
  144.  
  145.  
  146.   I would be happy to receive any bug-reports andideas for future versions!
  147.  
  148.  
  149.  
  150.  
  151.  
  152.